home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / mann / selection.n < prev    next >
Text File  |  1994-09-20  |  10KB  |  321 lines
  1. '\"
  2. '\" Copyright (c) 1990-1992 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/selection.n,v 1.8 93/04/01 09:52:55 ouster Exp $ SPRITE (Berkeley)
  22. '/" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS selection tk
  206. .BS
  207. '\" Note:  do not modify the .SH NAME line immediately below!
  208. .SH NAME
  209. selection \- Manipulate the X selection
  210. .SH SYNOPSIS
  211. \fBselection \fIoption\fR ?\fIarg arg ...\fR?
  212. .BE
  213.  
  214. .SH DESCRIPTION
  215. .PP
  216. This command provides a Tcl interface to the X selection mechanism and
  217. implements the full selection functionality described in the
  218. X Inter-Client Communication Conventions Manual (ICCCM), except that it
  219. supports only the primary selection.
  220. .PP
  221. The first argument to \fBselection\fR determines the format of the
  222. rest of the arguments and the behavior of the command.  The following
  223. forms are currently supported:
  224. .TP
  225. \fBselection clear \fIwindow\fR
  226. .VS
  227. If there is a selection anywhere on \fIwindow\fR's display, clear it
  228. so that no window owns the selection anymore.  Returns an empty string.
  229. .VE
  230. .TP
  231. \fBselection get \fR?\fItype\fR?
  232. Retrieves the value
  233. of the primary selection and returns it as a result.
  234. \fBType\fR specifies the form in which the selection is to be
  235. returned (the desired ``target'' for conversion, in ICCCM
  236. terminology), and should be an
  237. atom name such as STRING or FILE_NAME;  see the Inter-Client
  238. Communication Conventions Manual for complete details.
  239. \fBType\fR defaults to STRING.  The selection owner may choose to
  240. return the selection in any of several different representation
  241. formats, such as STRING, ATOM, INTEGER, etc. (this format is
  242. different than the selection type;  see the ICCCM for all the
  243. confusing details).  If the selection is returned in
  244. a non-string format, such as INTEGER or ATOM, the \fBselection\fR
  245. command converts it to string format as a collection of fields
  246. separated by spaces:  atoms are converted to their
  247. textual names, and anything else is converted to hexadecimal
  248. integers.
  249. .TP
  250. \fBselection handle \fIwindow command \fR?\fItype\fR? ?\fIformat\fR?
  251. Creates a handler for selection requests, such that \fIcommand\fR will
  252. be executed whenever the primary selection is
  253. owned by \fIwindow\fR and someone attempts to retrieve it in the form
  254. given by \fItype\fR (e.g. \fItype\fR is specified in the \fBselection get\fR
  255. command).  \fIType\fR defaults to STRING.
  256. .VS
  257. If \fIcommand\fR is an empty string then any existing handler for
  258. \fIwindow\fR and \fItype\fR is removed.
  259. .VE
  260. .RS
  261. .PP
  262. When the selection is requested and \fIwindow\fR is the selection owner
  263. and \fItype\fR is the requested type, \fIcommand\fR will be executed
  264. as a Tcl command with two additional numbers appended to it
  265. (with space separators).  The two additional numbers
  266. are \fIoffset\fR and \fImaxBytes\fR:  \fIoffset\fR specifies a starting
  267. character position in the selection and \fImaxBytes\fR gives the maximum
  268. number of bytes to retrieve.  The command should return a value consisting
  269. of at most \fImaxBytes\fR of the selection, starting at position
  270. \fIoffset\fR.  For very large selections (larger than \fImaxBytes\fR)
  271. the selection will be retrieved using several invocations of \fIcommand\fR
  272. with increasing \fIoffset\fR values.  If \fIcommand\fR returns a string
  273. whose length is less than \fImaxBytes\fR, the return value is assumed to
  274. include all of the remainder of the selection;  if the length of
  275. \fIcommand\fR's result is equal to \fImaxBytes\fR then
  276. \fIcommand\fR will be invoked again, until it eventually
  277. returns a result shorter than \fImaxBytes\fR.  The value of \fImaxBytes\fR
  278. will always be relatively large (thousands of bytes).
  279. .PP
  280. If \fIcommand\fR returns an error then the selection retrieval is rejected
  281. .VS
  282. just as if the selection didn't exist at all.
  283. .VE
  284. .PP
  285. The \fIformat\fR argument specifies the representation that should be
  286. used to transmit the selection to the requester (the second column of
  287. Table 2 of the ICCCM), and defaults to STRING.  If \fIformat\fR is
  288. STRING, the selection is transmitted as 8-bit ASCII characters (i.e.
  289. just in the form returned by \fIcommand\fR).  If \fIformat\fR is
  290. ATOM, then the return value from \fIcommand\fR is divided into fields
  291. separated by white space;  each field is converted to its atom value,
  292. and the 32-bit atom value is transmitted instead of the atom name.
  293. For any other \fIformat\fR, the return value from \fIcommand\fR is
  294. divided into fields separated by white space and each field is
  295. converted to a 32-bit integer;  an array of integers is transmitted
  296. to the selection requester.
  297. .PP
  298. The \fIformat\fR argument is needed only for compatibility with
  299. selection requesters that don't use Tk.  If the Tk toolkit is being
  300. used to retrieve the selection then the value is converted back to
  301. a string at the requesting end, so \fIformat\fR is
  302. irrelevant.
  303. .RE
  304. .TP
  305. \fBselection own \fR?\fIwindow\fR? ?\fIcommand\fR?
  306. .VS
  307. If \fIwindow\fR is specified, then it becomes the new selection owner
  308. and the command returns an empty string as result.
  309. The existing owner, if any, is notified that it has lost the selection.
  310. If \fIcommand\fR is specified, it is a Tcl script to execute when
  311. some other window claims ownership of the selection away from
  312. \fIwindow\fR.
  313. If neither \fIwindow\fR nor \fIcommand\fR is specified then
  314. the command returns the path name of the window in this application
  315. that owns the selection, or an empty string if no window in this
  316. application owns the selection.
  317. .VE
  318.  
  319. .SH KEYWORDS
  320. clear, format, handler, ICCCM, own, selection, target, type
  321.